* A PAM module that updates the dovecot cram-md5 password file
** Introduction

This PAM module hooks into password changes, and updates the cram-md5
file, used by the dovecot IMAP deamon, for cram-md5 authentication,
when PAM is used to change a user's password.

This PAM module has only been tested out in debian:
 - Originally built and tested on debian Wheezy (debian stable in May 2013)
 - Used as-is on debian Jessie when the system was upgraded
 - Recompiled on a 64bit debian Jessie system. The old .so failed to load, message in /var/log/auth.log :
   : PAM unable to dlopen(pam_dovecotmd5pwd.so): /lib/security/pam_dovecotmd5pwd.so: wrong ELF class: ELFCLASS32

** Requirements

This module should work on all GNU/linux systems with dovecot and the libpam development files (PAM itself is AFAIK part of all GNU/linux distributions).

To install the requirements on a debian system, type the following in a root command line shell:
#+BEGIN_EXAMPLE
  apt-get install dovecot-imapd libpam0g-dev
#+END_EXAMPLE

** Installation

To build the module, type:
: make

To install the module, as root, either do:
: make install
or, after building, simply do:
: cp pam_dovecotmd5pwd.so /lib/security/

The final part is to add the new module to the
=/etc/pam.d/common-password= file.  Add the following line in a
suitable place:
: password	required			pam_dovecotmd5pwd.so

I'm not entirely sure of where in the file to put it, but the comments
in =/etc/pam.d/common-password= say:
#+begin_example
  # As of pam 1.0.1-6, this file is managed by pam-auth-update by default.
  # To take advantage of this, it is recommended that you configure any
  # local modules either before or after the default block, and use
  # pam-auth-update to manage selection of other modules.  See
  # pam-auth-update(8) for details.
#+end_example

From that comment, what I've done is put the config for the new
module, after the line
: # end of pam-auth-update config

I.e. like so:
#+begin_example
  ...
  # end of pam-auth-update config
  
  # Update cram-md5 passwords for dovecot
  password        required                        pam_dovecotmd5pwd.so
#+end_example


** TODO-list
 - Read the cram-md5 password list from the dovecot configuration
 - Use the same library as "doveadm pw" to create the hashed password,
   instead of starting a subprocess

** License

This PAM module software is released under the [[http://www.gnu.org/licenses/gpl-2.0.html][GPLv2]]:
#+begin_example
  Copyright (C) 2013  Steinar Bang
  
  This program is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 2
  of the License, or (at your option) any later version.
  
  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
#+end_example

The full text of the license can be found in the file =LICENSE=.
